// Package res 提供了统一的HTTP响应处理工具函数
// 该包封装了常见的JSON响应格式，包括成功响应和失败响应
package res

import "github.com/gin-gonic/gin"

// Response 定义了统一的API响应结构体
// 所有API响应都将遵循这个格式
// Code: 响应状态码，0表示成功，其他值表示不同的错误类型
// Msg: 响应消息，描述操作结果或错误信息
// Data: 响应数据，可包含任意类型的返回数据
type Response struct {
	Code int    `json:"code"` // 状态码，0表示成功
	Msg  string `json:"msg"`  // 响应消息
	Data any    `json:"data"` // 响应数据，可以是任意类型
}

// response 是一个内部辅助函数，用于生成标准的JSON响应
// 参数：
//   - c: Gin上下文对象，用于处理HTTP请求和响应
//   - code: 状态码，0表示成功，其他值表示不同的错误类型
//   - data: 响应数据，可包含任意类型的返回数据
//   - msg: 响应消息，描述操作结果或错误信息
func response(c *gin.Context, code int, data any, msg string) {
	// 使用Gin的JSON方法返回JSON格式的响应
	// 参数1: HTTP状态码，固定为200表示请求处理成功
	// 参数2: 响应数据，使用Response结构体包装
	c.JSON(200, Response{
		Code: code, // 设置响应状态码
		Data: data, // 设置响应数据
		Msg:  msg,  // 设置响应消息
	})
}

// codeMap 是一个错误码到错误消息的映射表
// 用于根据错误码获取对应的错误描述
// key: 错误码
// value: 对应的错误消息
var codeMap = map[int]string{
	1001: "权限错误", // 权限相关的错误
	1002: "角色错误", // 角色相关的错误
}

// OK 返回成功响应，包含数据和消息
// 参数：
//   - c: Gin上下文对象，用于处理HTTP请求和响应
//   - data: 要返回的数据，可以是任意类型
//   - msg: 成功消息，描述操作结果
func OK(c *gin.Context, data any, msg string) {
	// 调用内部辅助函数生成成功响应
	// 状态码为0表示成功
	response(c, 0, data, msg)
}

// OKWithData 返回只包含数据的成功响应
// 消息默认为"ok"
// 参数：
//   - c: Gin上下文对象，用于处理HTTP请求和响应
//   - data: 要返回的数据，可以是任意类型
func OKWithData(c *gin.Context, data any) {
	// 调用OK函数返回成功响应
	// 消息固定为"ok"
	OK(c, data, "ok")
}

// OKWithMsg 返回只包含消息的成功响应
// 数据为空的map
// 参数：
//   - c: Gin上下文对象，用于处理HTTP请求和响应
//   - msg: 成功消息，描述操作结果
func OKWithMsg(c *gin.Context, msg string) {
	// 调用OK函数返回成功响应
	// 数据为空map，消息为传入参数
	OK(c, gin.H{}, msg)
}

// Fail 返回失败响应，包含错误码、数据和消息
// 参数：
//   - c: Gin上下文对象，用于处理HTTP请求和响应
//   - code: 错误码，表示不同的错误类型
//   - data: 错误相关数据，可以是任意类型
//   - msg: 错误消息，描述错误信息
func Fail(c *gin.Context, code int, data any, msg string) {
	// 调用内部辅助函数生成失败响应
	response(c, code, data, msg)
}

// FailWithMsg 返回只包含错误消息的失败响应
// 错误码固定为-100，数据为nil
// 参数：
//   - c: Gin上下文对象，用于处理HTTP请求和响应
//   - code: 原始错误码（会被覆盖为-100）
//   - msg: 错误消息，描述错误信息
func FailWithMsg(c *gin.Context, code int, msg string) {
	// 调用内部辅助函数生成失败响应
	// 状态码固定为-100，数据为nil
	response(c, -100, nil, msg)
}

// FailWithCode 根据预定义的错误码返回失败响应
// 会从codeMap中查找对应的错误消息，如果未找到则返回"未知错误"
// 参数：
//   - c: Gin上下文对象，用于处理HTTP请求和响应
//   - code: 预定义的错误码
func FailWithCode(c *gin.Context, code int) {
	// 从错误码映射表中获取对应的错误消息
	msg, ok := codeMap[code]
	if !ok {
		// 如果未找到对应的错误消息，则使用默认消息"未知错误"
		msg = "未知错误"
	}
	// 调用内部辅助函数生成失败响应
	// 状态码固定为-100，数据为nil
	response(c, -100, nil, msg)
}
